feat: pass the client address and refused user to SFTP handshake errors - #296

Motivation

A server built on sftp.Server gets SSHKeyExchangeError for every failed
handshake, and Logger.Error gets only the error. Its text names neither the
client address nor the user. When a client resets the connection after a
refused password, the error is a bare *net.OpError and the refusal is not
visible at all. A server cannot record a refused login, or tell it from a
dropped connection, from that error.

Context: miniohq/aistor#8879 (refused FTP and SFTP logins leave no audit entry,
API-log record or counter). This is a cross-repo reference, not a closing one.

Change

Logger.Error(SSHKeyExchangeError, err) now receives a *HandshakeError:

• Addr: the remote address of the TCP connection (behind a TCP proxy, the
  proxy's address).
• User: the name the client sent with the last authentication attempt the
  server decided. A none attempt that fails with ssh.ErrNoAuth offers no
  credential and does not count.
• Refused: true when the server refused that attempt, including when its
  callback failed for another reason, such as an unreachable backend or a
  client that hung up at a prompt. A partial success is not a refusal.
• Err: the handshake error. Error() returns its text unchanged, and
  Unwrap returns it.

handleConnection hands ssh.NewServerConn a copy of the SSH config whose
AuthLogCallback records the user and the verdict of each attempt. x/crypto
calls it with the final verdict of every method: after the source-address
check, after VerifiedPublicKeyCallback, for the key algorithm list, and for
the callbacks a PartialSuccessError installs. An AuthLogCallback the
caller set still runs, with the same arguments. One connection's callbacks run one after
another on its handshake goroutine, so the state needs no lock or map. The
Logger interface and the callbacks' results do not change.

Known limit: a public key signature that fails verification ends the handshake
before x/crypto calls AuthLogCallback. User and Refused then describe the
last attempt the server decided before it, and Err holds the verification
error. When the forged signature comes first, User is empty and Refused is
false; the previous head reported the key's user there.

The package had no test file, so sftp/sftp_test.go is new.

Validation

Run on this branch (base minio/pkg main fb13bfe):

• go test -race -tags kqueue -count=5 ./sftp: 100 of 100 test results passed
  (TestHandshakeError with 18 subtests, and TestHandshakeErrorNilErr). A
  run with -count=30 -cpu=1,4 also passed. go test -race -tags kqueue ./...: all packages passed.
• The subtests cover a refused password, key and keyboard-interactive login;
  two refused keys (one error); a refused then valid login (no error); a
  refusal by the source-address check, by VerifiedPublicKeyCallback, by a
  second factor after a partial success, by the key algorithm list, and by a
  NoClientAuthCallback; a wrapped PartialSuccessError (a refusal, as in
  x/crypto); a client that hangs up at a prompt (refused); a partial success
  the client abandons (not refused); a forged signature; a client with no credential;
  the exact calls a caller's AuthLogCallback receives; connect and close
  (with Addr); and a protocol failure.
• Against the previous head (8bcdd39), 6 of these subtests fail.
• Mutation checks, 12 of 12 caught, among them: a wrapped partial success
  treated as partial, a partial success counted as a refusal, five ways of
  calling the caller's AuthLogCallback wrongly (dropped, only for none,
  twice, skipping none, with a nil error), none always or never skipped,
  User not recorded, a hang-up exempted from refusal, and Addr set to the
  local address.
• make lint: 0 issues. gofumpt, go vet -tags kqueue ./sftp and typos:
  clean. go build ./... on the branch merged into main: ok.
• End to end, an aistor build at 72219f422 with a replace to this branch
  and a print of the HandshakeError fields: refused password (known and
  unknown user) and refused key gave one error with refused=true and the
  user, on 3 of 3 runs each. Valid logins, including two refused keys then a
  valid password, gave none. Connect and close gave refused=false with no
  user. The previous head gave the same results on these six cases. Cases
  that differ from the previous head, such as a forged signature or a refused
  key algorithm, ran only in the unit tests.
• CodeRabbit local deep review: 0 findings.

Not run: a client with keyboard-interactive or GSSAPI against a real aistor
server.

Compatibility

Error() returns the same text as before. A logger that prints the error's
type now sees *sftp.HandshakeError; aistor's logger prints %v (%T), so
that suffix changes. A logger that type-asserts the error as *net.OpError or
compares it with == no longer matches, and should use errors.As or
errors.Is.

Summary by CodeRabbit

• New Features
  • SFTP handshake errors now include the remote address and, when available, the most recently offered username and whether its credentials were rejected.
  • Errors distinguish authentication refusals from other handshake failures, such as a closed connection or malformed input.
  • Handshake errors retain access to the underlying error for additional context.
  • Partial authentication success is not classified as a refusal, and existing authentication logging continues to work.